Added AGENTS.md instructions and SKILLS.md#1921
Conversation
A global general instruction and one per project JAVA-6143
rozza
changed the title
|
Followed general guidelines from: https://wiki.corp.mongodb.com/spaces/MMS/pages/499158370/Making+a+Repo+Agent+Ready AGENTS.md: The ConstitutionAGENTS.md is a markdown file at the root of the repository. Every AI agent — Augment, Claude Code, Cursor — reads it automatically at the start of every session. This means every token in AGENTS.md is loaded into the agent's context window every single time. The context window has a budget. Frontier models reliably follow ~150-200 instructions, and tool system prompts consume a significant share before your AGENTS.md even loads. Overstuffing AGENTS.md degrades the quality of all instructions — not selectively. Brevity is load-bearing. What belongs in AGENTS.mdCore development principles (style, testing, safety rules) What does NOT belong in AGENTS.mdDetailed workflows for specific tasks (use a skill) |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 52 out of 53 changed files in this pull request and generated 5 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
rozza
requested review from
katcharov and
strogiyotec
and removed request for
strogiyotec
|
We had a bit of discussion about this in the AI/ML-sync meeting yesterday. My approach has been to use very minimal agents files (for Junie, Augie, and Claude) because I don't think it is clear what is:
I think we've all seen harmful changes--for example, telling it about tests and then having the agent get caught up attempting to run them all the time. Things that are not harmful but also not very useful (the benign category) can end up being accidentally harmful by taking up context space and thereby forcing something important out. We can discuss these things on a case-by-case basis, but I think that means starting small and understanding the impacts of the changes made. Another approach is for each platform team to do something different and then we all compare notes later. |
katcharov
left a comment
katcharov
left a comment
There was a problem hiding this comment.
Partial review. Agree with @ajcvickers points above. There is a fair bit of content here, and I am not sure how we can validate it.
There was a problem hiding this comment.
Could you run Claude to review this PR, asking something like "Confirm that this PR follows best practices for creating CLAUDE.md files. Evaluate it personally, confirming that various items are generally necessary. Also evaluate it based on official and authoritative sources (official Claude documentation, online posts that are corroborated AND experimentally verified, and posts from recognized experts; but not: blog posts, social media speculations, and other uncorroborated sources. Is anything unnecessary, and easily discoverable? Is anything crucial missing?"
Independently, have it doublecheck correctness until it stops finding issues.
Please also include info about how these files were generated, and AI-reviewed, including results of the above. (This is just the typical AI usage, effectiveness comment in the description).
There was a problem hiding this comment.
|
@ajcvickers thanks for the feedback. Out of interest were the MMS team in the AI/ML-sync meeting? The formating of this PR and use of skills over a large Claude.md file came via Glean indiciating the Cloud teams approach : https://wiki.corp.mongodb.com/spaces/MMS/pages/499158370/Making+a+Repo+Agent+Ready They seem to be a few months ahead with their adoption and usage of these tools. @katcharov know anyone on their team that could review this. |
|
So I think before going further, an ideological approach has to be agreed upon. Do we add skills at all initially? We could .gitignore the skills directory and then manually add them on a one by one basis in other PR's? That approach is handy and would allow users to have test their own skills without risk of accidently adding to the repo. Note the request for local skills anthropics/claude-code#31155 has been closed so there is no local repo skills pattern other than via .gitignore. We can start small - just the AGENTS.md files explaining the source code and how to compile and run the tests. This is useful to stop claude trying to use sbt instead of gradle everytime it tries to do anything in scala.
|
|
I made some changes after iterating with Claude. Full report of the final outcomes: https://gist.github.com/rozza/1a474291735bac0a28e399c59a977db2 |
|
|
||
| - **Static analysis:** CodeNarc | ||
|
|
||
| ## Javadoc / KDoc / Scaladoc |
There was a problem hiding this comment.
Claude identified these as missing
| description: Sync AGENTS.md files and skills after buildSrc or convention changes. Use after modifying build plugins, formatting rules, testing conventions, or task names to keep documentation consistent. | ||
| disable-model-invocation: true | ||
| --- | ||
| # Sync Documentation After Build Changes |
There was a problem hiding this comment.
Claude identified the buildSrc/AGENTS.md was not the correct place for this as it changes code. It also recommended this not be automatically run by claude.
| @@ -0,0 +1,88 @@ | |||
| # Test Skeletons | |||
There was a problem hiding this comment.
Claude recommended having official test skeleton examples to use for new test cases.
There was a problem hiding this comment.
Claude recommended deleting a few AGENTS.md files as they didnt add value or were for niche projects within the codebase.
| ./gradlew :bson-kotlin:check | ||
| ``` | ||
|
|
||
| For global rules see [root AGENTS.md](../AGENTS.md). |
There was a problem hiding this comment.
These comments were considered unnecessary because the root agent is already in scope.
|
@rozza I think you should continue with this approach and on the C# driver we will start more minimal, and then let's revisit how things are working in a few weeks. |
|
@katcharov please re-review. See: https://gist.github.com/rozza/1a474291735bac0a28e399c59a977db2 for the claude report on the latest iteration. |
rozza
requested review from
dariakp and
nhachicha
and removed request for
katcharov
Initial implementation of AGENTS.md and SKILLS.md for the MongoDB Java Driver Repo
JAVA-6143